---
title: 환경 변수
description: Hollo 설정에 쓰이는 환경 변수들에 대해 설명합니다.
---

import { Aside, Badge } from '@astrojs/starlight/components';

Hollo는 환경 변수를 통해 여러 가지 설정을 할 수 있습니다.
환경 변수는 프로젝트 최상위 디렉터리에 *.env* 파일을 만들거나,
Docker의 `-e`/`--env` 옵션을 쓰거나,
Railway의 environment variables 메뉴에서 설정할 수 있습니다.


기본 설정
---------

### `PORT` <Badge text="선택" /> <Badge text="Railway에서는 안 쓰임" variant="tip" />

서버가 수신할 포트 번호. 기본값은 3000입니다.

### `BIND` <Badge text="선택" /> <Badge text="Railway에서는 안 쓰임" variant="tip" />

서버가 수신할 주소. 유효한 IP 주소나 `localhost`여야 합니다.

### `DATABASE_URL` <Badge text="Railway에서는 안 쓰임" variant="tip" />

PostgreSQL 데이터베이스의 URL. 예: `postgresql://hollo:password@localhost/hollo`.

### `SECRET_KEY` <Badge text="Railway에서는 안 쓰임" variant="tip" />

세션을 보호하기 위한 비밀 키. 최소 44자 이상이어야 합니다.
다음 명령어로 안전한 무작위 비밀 키를 생성 가능합니다:

~~~~ sh frame="none"
openssl rand -hex 32
~~~~

### `TZ` <Badge text="선택" />

애플리케이션의 시간대(time zone). 유효한 시간대 식별자여야 합니다.
예: `UTC`, `America/New_York`, `Asia/Seoul`.

기본값은 `UTC`입니다.

### `BEHIND_PROXY` <Badge text="선택" /> <Badge text="Railway에서는 안 쓰임" variant="tip" />

Hollo가 리버스 프록시 뒤에 있는 경우 `true`로 설정하세요.
Hollo가 L7 로드 밸런서 뒤에 위치할 경우 (일반적으로 그래야 합니다), 이 옵션을 켜세요.

기본적으로는 꺼져 있습니다.

<Aside>
  이 옵션을 켜면, Hollo는 리버스 프록시로부터 전달 받은 `X-Forwarded-For`,
  `X-Forwarded-Proto`, `X-Forwarded-Host` 헤더를 신뢰합니다.
  이 동작은 보안상 주의를 기울여야 합니다.
</Aside>

### `ALLOW_PRIVATE_ADDRESS` <Badge text="선택" />

이 옵션을 `true`로 설정하면 서버 측 요청 위조(SSRF) 공격 방지를 풉니다.

로컬 네트워크에서 테스트할 때 이 옵션을 켜야 할 수 있습니다.

기본적으로는 꺼져 있습니다.

<Aside>
  이 옵션을 켜는 것은 보안상 위험할 수 있습니다. 신뢰할 수 있는 환경에서만 사용하고,
  프로덕션 환경에서는 사용하지 마세요.
</Aside>


부가 기능
---------

###  `HOME_URL` <Badge text="선택" />

설정될 경우, 첫 페이지 접속 시 이 URL로 리다이렉트됩니다. 설정되지 않을 경우,
첫 페이지에서 인스턴스 내 계정 목록이 보입니다.

### `REMOTE_ACTOR_FETCH_POSTS` <Badge text="선택" />

원격 액터와 처음으로 조우하게 되었을 때 가져올 최신 공개 게시물의 수.

기본값은 `10`입니다.

### `TIMELINE_INBOXES` <Badge text="선택" />

이 옵션을 `true`로 설정하면 타임라인이 수신함처럼 작동합니다. 즉, 타임라인에
표시될 게시물들이 실시간으로 필터링되는 것이 아니라, 미리 추출된 게시물들이
데이터베이스에 저장됩니다. 이 기능은 많은 원격 게시물을 수신하는 상대적으로
큰 인스턴스에서 유용합니다.

Hollo 0.4.0 시점에서 이 기능은 실험적이며, 버그가 있을 수 있습니다. 하지만
이 기능은 안정화된 뒤에 기본 동작으로 바뀔 예정입니다.

기본적으로는 꺼져 있습니다.

### `ALLOW_HTML` <Badge text="선택" />

이 옵션을 `true`로 설정하면 날 HTML을 Markdown 사이에 쓸 수 있습니다.
(Markdown은 Hollo에서 프로필 소개나 게시물 내용 등에 사용됩니다.)
Markdown에서 지원하는 서식보다 더 다양한 서식을 사용하고 싶을 때 유용하지만,
XSS 공격을 막기 위해 HTML 태그와 속성이 어느 정도 제한됩니다.

기본적으로는 꺼져 있습니다.


로그 및 디버그
--------------

### `LOG_LEVEL` <Badge text="선택" />

애플리케이션의 로그 레벨.
`debug`, `info`, `warning`, `error`, `fatal` 중 택일.

기본값은 `info`입니다.

### `LOG_QUERY` <Badge text="선택" />

SQL 쿼리를 로그에 남기려면 `true`로 설정하세요.

기본값은 `false`입니다.

### `LOG_FILE` <Badge text="선택" />

구조화된 로그를 쓸 파일의 경로를 지정하세요.  콘솔에 출력되는 로그와는 다르게,
이 로그는 JSON Lines 형식으로 기록됩니다.

### `SENTRY_DSN` <Badge text="선택" />

오류 리포트와 트레이스를 보낼 Sentry 프로젝트의 DSN.


미디어 저장소
-------------

### `DRIVE_DISK`

Hollo에서 프로필 사진, 커스텀 에모지, 기타 미디어와 같은 파일들을 저장할
디스크 드라이버.

선택지는 `fs` (로컬 파일시스템) 또는 `s3` (S3 호환 오브젝트 스토리지) 중
하나입니다.

하위 호환성을 위해 `s3`가 기본값이지만, 앞으로는 기본값이 사라질 예정이므로
명시적으로 설정하는 것이 좋습니다.

드라이버에 관해 자세히 알아보려면 [FlyDrive 문서][](영문)를 참고하세요.

<Aside type="caution">
  운영중인 Hollo의 `DRIVE_DISK` 및 관련 설정을 도중에 변경하더라도, 기존
  파일들은 옮겨지지 않습니다. 새로운 파일들만 새로운 설정에 따라 저장됩니다.

  또한, 기존 파일들은 여전히 예전의 설정에 따라 서빙되므로, 이 점을 유의하세요.
  예를 들어, `S3_BUCKET`을 바꿨어도, 기존 파일들은 예전의 버킷에서 서빙되므로
  지우면 안 됩니다.
</Aside>

[FlyDrive 문서]: https://flydrive.dev/docs/drive_manager

### `STORAGE_URL_BASE`

미디어 파일들을 서빙할 URL의 앞 부분. 예: `https://media.hollo.social`.

`DRIVE_DISK=fs`인 경우, 로컬 파일시스템에 저장된 파일들을 웹에서 접근할 수 있도록 하려면
`https://<호스트>/assets` 형태로 설정해야 합니다.
예: `https://hollo.example.com/assets`.

<Aside type="caution">
  - 실제 운영시에는 HTTPS를 사용해야 합니다.
  - 공개적으로 접근 가능해야 연합이 올바르게 작동합니다.
  - 유연성을 위해 오브젝트 스토리지의 실제 도메인을 직접 쓰는 대신, `CNAME`된 도메인을 사용하는
    것을 권장합니다.
</Aside>

### 로컬 파일시스템 설정

#### `FS_STORAGE_PATH` <Badge text="FS 드라이버에서 필수" variant="note" />

로컬 파일시스템에서 파일들을 저장할 경로. 예: `/var/lib/hollo`.

<Aside>
  - 디렉터리가 존재해야 하며 Hollo 프로세스가 쓸 수 있어야 합니다.
  - 권한 설정은 디렉터리의 경우 755, 파일들의 경우 644를 권장합니다.
  - 충분한 디스크 공간이 확보되어 있는지 확인하세요.
  - 필히 정기적인 백업을 하시기 바랍니다.
  - Docker를 쓸 때는 경로가 제대로 마운트되었는지 확인하세요.
</Aside>

### S3 호환 오브젝트 스토리지 설정

<Aside>
  이하의 설정들은 `DRIVE_DISK=s3`일 때만 필요합니다.

  AWS IAM 정책이 아래 권한들을 지니고 있는지 확인하세요:

  - `s3:PutObject`
  - `s3:GetObject`
  - `s3:DeleteObject`
  - `s3:ListBucket`
</Aside>

#### `S3_REGION` <Badge text="S3 드라이버에서 필수" variant="caution" />

S3 호환 오브젝트 스토리지의 지역. 예: `us-east-1`.
몇몇 AWS가 아닌 S3 호환 서비스에서는 이 값이 필요 없을 수 있습니다.

#### `S3_BUCKET` <Badge text="S3 드라이버에서 필수" variant="caution" />

S3 호환 오브젝트 스토리지의 버킷 이름. 예: `hollo`.

#### `S3_ENDPOINT_URL` <Badge text="S3 드라이버에서 필수" variant="caution" />

S3 호환 오브젝트 스토리지의 엔드포인트 URL.
예: `https://s3.us-east-1.amazonaws.com`.

#### `S3_FORCE_PATH_STYLE` <Badge text="선택" />

S3 호환 오브젝트 스토리지에 대해 경로 스타일 URL을 강제할지 여부 (`true` 혹은 `false`).
AWS가 아닌 S3 호환 서비스에서 유용합니다.
기본적으로는 꺼져 있습니다.

#### `AWS_ACCESS_KEY_ID` <Badge text="S3 드라이버에서 필수" variant="caution" />

S3 호환 오브젝트 스토리지 액세스 키.

#### `AWS_SECRET_ACCESS_KEY` <Badge text="S3 드라이버에서 필수" variant="caution" />

S3 호환 오브젝트 스토리지 비밀 키.
